<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en"><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><title>Balloon tip - Manual</title>

<link rel="stylesheet" href="style/style.css" type="text/css" /></head>
<body>
<div id="header" class="balloontip"> <img src="images/BalloonTip.png" alt="Balloon tip" />
<div id="title"> Manual <span id="releaseDate">v1.2.1</span></div>
</div>
<div class="section">
<div class="title"> Table of contents</div>
<ol>
<li><a href="#usage">Usage</a>
<ol>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#gettingstarted">Getting started</a></li>
<li><a href="#usingballoontip">Using BalloonTip</a>
<ol>
<li><a href="#simpleconstructor">My first
balloon tip</a></li>
<li><a href="#styleconstructor">Balloon
tips
with style</a></li>
<li><a href="#contentsconstructor">Use a
JComponent as contents</a></li>
<li><a href="#positionconstructor">Tweaking
a balloon tip's position</a></li>
<li><a href="#fullconstructor">Balloon
tips
with custom positioners</a></li>
</ol>
</li>
<li><a href="#othertypesofballoontips">Other
types of balloon tips</a>
<ol>
<li><a href="#customballoontip">CustomBalloonTip</a></li>
<li><a href="#tablecellballoontip">TablecellBalloonTip</a></li>
</ol>
</li>
<li><a href="#utilities">Utilities</a>
<ol>
<li><a href="#timedballoontips">Timed
balloon tips</a></li>
<li><a href="#fadeeffects">Fade effects</a></li>
<li><a href="#balloontooltips">Balloon
tooltips</a></li>
</ol>
</li>
</ol>
</li>
<li><a href="#development">Development</a>
<ol>
<li><a href="#importingtheproject">Importing
the project</a>
<ol>
<li><a href="#eclipsewithmavensupport">Eclipse,
with Maven support</a></li>
<li><a href="#eclipseregularjavaproject">Eclipse,
regular Java project</a></li>
<li><a href="#maven">Maven</a></li>
<li><a href="#ant">Ant</a></li>
</ol>
</li>
<li><a href="#creatingyourownballoontipstyle">Creating
your own BalloonTipStyle</a></li>
<li><a href="#creatingyourownballoontippositioner">Creating
your own BalloonTipPositioner</a></li>
</ol>
</li>
<li><a href="#releasenotes">Release notes</a></li>
</ol>
</div>
<div class="section">
<div class="title"> 1.&nbsp;Usage<a name="usage"></a></div>
<div class="subSection">
<div class="title">1.1.&nbsp;Requirements<a name="requirements"></a></div>
The only requirement to make use of&nbsp;Balloon tip is that you
need Java 1.5&nbsp;or higher.
</div>
<div class="subSection">
<div class="title">1.2.&nbsp;Getting started<a name="gettingstarted"></a></div>
<p> Thanks for giving&nbsp;Balloon tip a try! You can now
spice up your Java Swing applications with the balloon
tip components provided in this project. </p>
<p> Before diving in, let's take a quick look at the things that
are
included in the .zip-file you've just downloaded: </p>
<ul>
<li><strong>doc</strong>: Directory with the
project's documentation
<ul>
<li><strong>javadoc</strong> Javadoc
documentation</li>
<li><strong>manual</strong> This manual</li>
</ul>
</li>
<li><strong>src</strong>: Directory with the
project's source code</li>
<li><strong>balloontip- ... .jar</strong>: This
.jar
contains just the necessary files, nothing else.</li>
<li><strong>balloontip-examples- ... .jar</strong>:
This .jar also contains the project's source files and some example
applications. This file may be more useful if you haven't used the
project before.</li>
</ul>
<p> Now that you know what is available in this release, let's
get
familiar with the features Balloon tip has to offer. The quickest way
to do this is to try out the demo application. Simply double-click the
balloontip_with_examples_ ... .jar-file to open the demo application. </p>
<p> If this doesn't work, you'll have to open up a
console/command-line window and navigate into the Balloon
tip-directory.<br />Just enter the following command to start the demo application:
<code>java -jar balloontip-examples ... .jar</code><br />
(Replace the "..." with the right version number.) </p>
<div class="image"> <img style="width: 547px; height: 725px;" src="images/DemoApplication.PNG" alt="The balloon tip example application" /><br />
The demo application </div>
<p> Once the application has started, you can start exploring
many of Balloon tip's features.<br />
Just toy around with all possible settings and see what happens; this
probably is the easiest way to learn the terminology that is used by
the Balloon tip API. </p>
<p> Once you're done playing, you may proceed to the next
section, which will teach you the basics in creating your own
balloon tips. </p>
</div>
<div class="subSection">
<div class="title">1.3. Using BalloonTip<a name="usingballoontip"></a></div>
<div class="subSection">
<div class="title">1.3.1. My first balloon tip<a name="simpleconstructor"></a></div>
<p> The <code>BalloonTip</code> class implements a basic balloon tip which is suited for most uses. A <code>BalloonTip</code>
instance can attach itself to about any visual component: a <code>JButton</code>,
<code>JLabel</code>, <code>JTextField</code>,
... In order to create and show a <code>BalloonTip</code>
instance, all you need to do is construct one. Like most components in
Swing, the <code>BalloonTip</code> class comes with
several constructors.</p>
<p> Starting off with the easiest constructor:</p>
<p> <code>BalloonTip(JComponent attachedComponent, String
text)</code></p>
<p> The first parameter, <code>attachedComponent</code>,
is the <code>JComponent</code> you want to attach your
balloon tip to. The second
parameter, <code>text</code>, simply is the text you want
to show inside the balloon tip. <br />
For example, if the attached component were a <code>JButton</code>
called <code>myButton</code> and you want the balloon to
say "Hello world!", you should write:</p>
<p><code>BalloonTip myBalloonTip = new BalloonTip(myButton,
"Hello world!");</code></p>
<p>The newly created balloon tip would then look like this:</p>
<div class="image"> <img style="width: 143px; height: 99px;" src="images/SimpleExample.PNG" alt="A BalloonTip attached to a JButton" /><br />
A <code>BalloonTip</code> attached to a <code>JButton</code>
</div>
</div>
<div class="subSection">
<div class="title">1.3.2. Balloon tips with style<a name="styleconstructor"></a></div>
<p>If you want to have control over the balloon tip's looks, you
can try this constructor:</p>
<p> <code>BalloonTip(JComponent attachedComponent, String
text, BalloonTipStyle style, boolean useCloseButton)</code></p>
<p> The parameter <code>useCloseButton</code> is
easy: If true, a working close button is shown.<br />
The <code>style</code> parameter is more interesting; a <code>BalloonTipStyle</code>
defines the balloon tip's looks. Several different styles can be found
in the package <code>net.java.balloontip.styles</code>. As
an example, I'll make a <code>BalloonTip</code> with the
simplest style, the <code>EdgedBalloonStyle</code>,
which&nbsp;gives the balloon tip&nbsp;sharp corners:</p>
<p> <code>BalloonTipStyle edgedLook = new
EdgedBalloonStyle(Color.WHITE, Color.BLUE);<br />
BalloonTip myBalloonTip = new BalloonTip(myButton, "Hello world!",
edgedLook, true);</code></p>
<p> Now we'll get something looking like this:</p>
<div class="image"> <img src="images/Edged.png" alt="A BalloonTip with an EdgedBalloonStyle" /><br />
A <code>BalloonTip</code> with an <code>EdgedBalloonStyle</code>,
which
gives the balloon its sharp corners, a white background color and a
blue border </div>
</div>
<div class="subSection">
<div class="title">1.3.3. Use a JComponent
as&nbsp;contents<a name="contentsconstructor"></a></div>
<p>Balloon tips can also contain other components beside just
text. In fact, just about any <code>JComponent</code>
can serve as the contents of a balloon tip.<br />
The following constructor allows you to add a <code>JComponent</code>
as the contents of a balloon tip:</p>
<p><code>BalloonTip(JComponent attachedComponent,
JComponent contents, BalloonTipStyle style, boolean useCloseButton)</code></p>
<p>For example, you could set a balloon tip's contents to a
<code>JTable</code>:</p>
<p><code>BalloonTipStyle edgedLook = new
EdgedBalloonStyle(Color.WHITE, Color.BLUE);<br />
BalloonTip myBalloonTip = new BalloonTip(myButton, new JTable(3,2),
edgedLook, true);</code></p>
<p>This creates the following result:</p>
<div class="image"> <img style="width: 166px; height: 114px;" src="images/TableExample.PNG" alt="A BalloonTip with an EdgedBalloonStyle" /><br />
A <code>BalloonTip</code> with a <code>JTable&nbsp;</code>as
its contents </div>
<span style="font-style: italic;">Tip</span>: If you
use components such as a <code>JPanel</code> or <code>JTabbedPane</code>,
you can build entire interactive user interfaces inside a balloon tip.
(Why yes, you can even attach balloon tips to the components inside a
balloon tip!)
</div>
<div class="subSection">
<div class="title">1.3.4. Tweaking a balloon tip's position<a name="positionconstructor"></a></div>
<p>If you also need control over the balloon tip's position, you
can use the following constructor:</p>
<p><code>BalloonTip(JComponent attachedComponent,
JComponent contents, BalloonTipStyle style, Orientation orientation,
AttachLocation
attachLocation, int horizontalOffset, int verticalOffset, boolean
useCloseButton)</code></p>
<p>This constructor has four new parameters:</p>
<ul>
<li><code>orientation</code>: Determines whether
you want the tip of the balloon on the left or right side of the
balloon, and whether the balloon itself should be above or below the
attached component</li>
<li><code>attachLocation</code>: Should the balloon
tip align itself with the attached component? Or should it put the
balloon's tip on a fixed location? (e.g. fix the balloon's tip
in the center of the attached component)</li>
<li><code>horizontalOffset</code>: The amount of
space (in pixels) between the balloon's left (or right) side and the
tip of the balloon</li>
<li><code>verticalOffset</code>: The amount of
space (in pixels) between the balloon's bottom (or top) side and the
tip of the balloon</li>
</ul>
<p>In order to clarify the <code>horizontalOffset</code>
and <code>verticalOffset</code> parameters a bit better,
have a look at this picture:</p>
<div class="image"> <img src="images/Offsets.png" alt="The horizontal and vertical offset of a BalloonTip" /><br />
The horizontal and vertical offset of a <code>BalloonTip</code>
</div>
<p>Here's a snippet of code that creates a balloon tip using this
constructor:</p>
<p> <code>BalloonTipStyle edgedLook = new
EdgedBalloonStyle(Color.WHITE, Color.BLUE);<br />
BalloonTip myBalloonTip = new BalloonTip(myButton, new JLabel("Hello
world!"),
edgedLook, Orientation.RIGHT_BELOW, AttachLocation.ALIGNED, 40, 20,
false);</code></p>
<p>This snippet will produce the following picture:</p>
<div class="image"> <img src="images/RightBelowPositioner.png" alt="A BalloonTip with Orientation.RIGHT_BELOW and AttachLocation.ALIGNED" /><br />
A <code>BalloonTip</code> with <code>Orientation.RIGHT_BELOW</code>
and <code>AttachLocation.ALIGNED</code> </div>
</div>
<div class="subSection">
<div class="title">1.3.5. Balloon tips with custom
positioners<a name="fullconstructor"></a></div>
<p>Finally, if you want full control over your balloon tip,
use this constructor:</p>
<p> <code>BalloonTip(JComponent attachedComponent,
JComponent contents, BalloonTipStyle style, BalloonTipPositioner
positioner, boolean
useCloseButton)</code></p>
<p>Even though this constructor has fewer parameters than the
previous one from section <a href="#positionconstructor">1.3.4</a>,
it is more powerful. This is because of the <code>positioner</code>
parameter. A <code>BalloonTipPositioner</code> defines the
way a balloon tip should behave. More specifically: it determines where
a
balloon tip should position itself, whether the balloon tip should
flip, what happens when the balloon tip collides with something, ...<br />
What the previous constructors actually did was simply instantiating
the
appropriate <code>BalloonTipPositioner</code> for you.
However, this constructor will allow you to supply your own instance of
<code>BalloonTipPositioner</code>.
Here's another example snippet that produces exactly the same
result as the example in the previous section:</p>
<p> <code>BalloonTipStyle edgedLook = new
EdgedBalloonStyle(Color.WHITE, Color.BLUE);<br />
BalloonTipPositioner rightBelowPositioner = new
Right_Below_Positioner(40, 20);<br />
BalloonTip myBalloonTip = new BalloonTip(myButton, "Hello world!",
edgedLook, rightBelowPositioner, false);</code></p>
<p> This concludes the basic usage of <code>BalloonTip</code>.
The other methods <code>BalloonTip</code> has to offer
should now be quite straightforward to use. If you require more
information, you can always refer to the
project's Javadoc.<br />
</p>
</div>
</div>
<div class="subSection">
<div class="title">1.4. Other types of balloon tips<a name="othertypesofballoontips"></a></div>
<div class="subSection">
<div class="title">1.4.1. CustomBalloonTip<a name="customballoontip"></a></div>
<p>The <code>CustomBalloonTip</code> is just like a
regular <code>BalloonTip</code>, but you can attach it to
a rectangular shape within a component, instead of attaching it to the
entire component. </p>
<p>This can be very useful in case you're creating your own <code>JComponent</code>,
such as a timeline or a calendar.</p>
<div class="image"> <img src="images/CustomBalloonTip.png" alt="An application with a custom JComponent that displays a timeline; it has a CustomBalloonTip attached to it" /><br />
An application with a custom <code>JComponent</code> that
displays a timeline; it has a <code>CustomBalloonTip</code>
attached to it </div>
<p>Just take a look at this snippet of code, which was used in
the demo application, just to see how it&nbsp;works:</p>
<pre><code>// Create a custom JComponent that draws a huge white canvas with a small blue rectangle in it<br />final Rectangle customOffset = new Rectangle(640, 320, 50, 16);<br />final JComponent customComponent = new JComponent() {<br />	protected void paintComponent(Graphics g) {<br />		Rectangle clip = g.getClipBounds();<br />		g.setColor(Color.WHITE);<br />		g.fillRect(clip.x, clip.y, clip.width, clip.height);<br />		g.setColor(Color.BLUE);<br />		g.fillRect(customOffset.x, customOffset.y, customOffset.width, customOffset.height);<br />	}<br />};<br />customComponent.setPreferredSize(new Dimension(1280, 640));<br /><br />// Now create the CustomBalloonTip, such that it attaches itself to the blue rectangle<br />customBalloon = new CustomBalloonTip(customComponent, <br />	"I'm a CustomBalloonTip!",<br />	customOffset,<br />	new EdgedBalloonStyle(Color.WHITE, Color.BLUE), <br />	BalloonTip.Orientation.LEFT_ABOVE, <br />	BalloonTip.AttachLocation.ALIGNED, <br />	20, 20, <br />	false);<br /></code></pre>
</div>
<div class="subSection">
<div class="title">1.4.2. TablecellBalloonTip<a name="tablecellballoontip"></a></div>
<p>A <code>TablecellBalloonTip</code> is a balloon
tip that attaches itself to a <code>JTable</code> cell.
The <code>TablecellBalloonTip</code> is very similar to a <code>CustomBalloonTip</code>:
Instead of specifying a rectangular offset, you&nbsp;specify a cell
row
and&nbsp;column. The row and column will determine which table cell
the
balloon tip should attach itself to.</p>
</div>
</div>
<div class="subSection">
<div class="title">1.5. Utilities<a name="utilities"></a></div>
<div class="subSection">
<div class="title">1.5.1. Timed balloon tips<a name="timedballoontips"></a></div>
<p>Any balloon tip can be automatically closed after a certain
period of time using the <code>TimingUtils</code> class.
Here's an example:</p>
<pre><code>BalloonTip balloonTip = new BalloonTip(someComponent, "I will dissapear in 3 seconds.");<br />// Now make the balloon tip disappear in 3000 milliseconds<br />TimingUtils.showTimedBalloon(balloonTip, 3000);</code></pre>
</div>
<div class="subSection">
<div class="title">1.5.2. Fade effects<a name="fadeeffects"></a></div>
<p>The <code>FadingUtils</code> class allows you to
add a simple linear fade-in or fade-out effect to balloon tips. An
example:</p>
<pre><code>BalloonTip balloonTip = new BalloonTip(someComponent, "I will fade in over 300 ms.");<br />// Perform a fade-in effect lasting 300 ms, at 24 frames per second and trigger finishedAction once the effect has finished<br />FadingUtils.fadeInBalloon(balloonTip, finishedAction, 300, 24);</code></pre>
<span style="font-style: italic;">Tip</span>: If you
desire something more complex than a linear function, you could
quite easily&nbsp;implement your own fade effects&nbsp;using
the <code>setOpacity</code> method of <code>BalloonTip</code>
in combination with, for example, <a href="http://java.net/projects/timingframework" target="_blank">timingframework</a>.
</div>
<div class="subSection">
<div class="title">1.5.3. Balloon tooltips<a name="balloontooltips"></a></div>
<p>You can turn any balloon tip into a tooltip with the <code>ToolTipUtils</code>class.
If you hover over the attached component, the balloon tip will
show up after an initial delay&nbsp;and&nbsp;then stay visible
until
the mouse no longer hovers over the component or a timeout occurs, just
like a regular tooltip. A quick
example:</p>
<p><code>tooltipBalloon = new BalloonTip(someComponent,
"I'm a balloon tooltip!");<br />
// Now convert this balloon tip to a tooltip, such that the tooltip
shows up after 500 milliseconds and stays visible for 3000 milliseconds<br />
ToolTipUtils.balloonToToolTip(tooltipBalloon, 500, 3000);</code></p>
</div>
</div>
</div>
<div class="section">
<div class="title"> 2. Development<a name="development"></a></div>
<div class="subSection">
<div class="title"> 2.1. Importing the project<a name="importingtheproject"></a></div>
<div class="subSection">
<div class="title">2.1.1. Eclipse, with Maven support
<a name="eclipsewithmavensupport"></a></div>
<p>Because Balloon tip is suited for use with Maven, it's quite
easy to
import
it as a Maven project into Eclipse. This&nbsp;can be done as
follows:</p>
<ol>
<li>In order to import Maven projects into Eclipse, you'll need
a plugin such as&nbsp;<a href="http://m2eclipse.sonatype.org/" target="_blank">m2eclipse</a>; install this first.</li>
<li>If you haven't already done so, download and unzip the
latest Balloon tip release from <a target="_blank" href="https://balloontip.dev.java.net">
https://balloontip.dev.java.net</a>.</li>
<li>In Eclipse, go to "File" &gt; "Import".</li>
<li>Select "Maven" &gt; "Existing Maven Projects".</li>
<li>Click "Next".</li>
<li>Click the "Browse" button next to "Root directory:" and
select the "src" directory from the unpacked Balloon tip release.</li>
<li>Click "Finish". The m2eclipse plugin will
import Balloon tip as 3 different projects: balloontip,
balloontip-examples and balloontip-parent:
<ul>
<li><span style="font-weight: bold;">balloontip</span>:
This is the most important project, as it contains all functionality of
Balloon tip.</li>
<li><span style="font-weight: bold;">balloontip-examples</span>:
This project contains a few examples that
demonstrate&nbsp;Balloon tip's functionality.</li>
<li><span style="font-weight: bold;">balloontip-parent</span>:
This parent project just groups balloontip and balloontip-examples. All
Maven goals that are executed on balloontip-parent will be executed on
both balloontip and balloontip-examples.</li>
</ul>
</li>
<li>All done! If all went well, you should be able to run
<code>net.java.balloontip.examples.complete.CompleteExample</code>
or any of the
other supplied examples in the balloontip-examples project.</li>
</ol>
<p>It doesn't matter much if you're not familiar with Maven; you
can use
the balloontip and balloontip-examples projects just like they were
regular Java projects. The only difference with regular projects is
that Maven projects have the added bonus of Maven's functionality,
which
is now at your disposal.</p>
</div>
<div class="subSection">
<div class="title">2.1.2. Eclipse, regular Java project
<a name="eclipseregularjavaproject"></a></div>
<p>You can import Balloon tip as a regular Java project by
following these steps:</p>
<ol>
<li>If you haven't already done so, download and unzip the
latest Balloon tip release from <a target="_blank" href="https://balloontip.dev.java.net/">
https://balloontip.dev.java.net/</a>.</li>
<li>In Eclipse, create a new empty Java project:
<ul>
<li>Go to "File" &gt; "New" &gt; "Java Project".</li>
<li>Type a project name and click "Finish".</li>
</ul>
</li>
<li>Now go to "File" &gt; "Import".</li>
<li>Select "General" &gt; "Archive File" and click "Next".</li>
<li>Click "Browse" and choose the balloontip-examples- ... .jar
file.</li>
<li>Click "Finish".</li>
<li>In the Package Explorer, expand your new project and drag
the "net" folder into the "src" folder.</li>
<li>All done! If all went well, you should be able to run
<code>net.java.balloontip.examples.complete.CompleteExample</code>
or any of the
other supplied examples.</li>
</ol>
</div>
<div class="subSection">
<div class="title">2.1.3. Maven
<a name="maven"></a></div>
<p>Balloon tip comes with its set of Maven POM files; you can use
them as follows:</p>
<ol>
<li>If you haven't already done so, download and unzip the
latest Balloon tip release from <a target="_blank" href="https://balloontip.dev.java.net/">
https://balloontip.dev.java.net/</a>.</li>
<li>Using your command-line-interface, navigate to the "src"
folder.</li>
<li>You're
now located inside the balloontip-parent module; it contains two
submodules: balloontip and balloontip-examples. To produce a .jar file
for each module, run the command&nbsp;<code>mvn package</code>.</li>
<li>If all went
well, you should now be able to run the example application by
executing src/balloontip-examples/target/balloontip-examples- ... .jar</li>
</ol>
</div>
<div class="subSection">
<div class="title">2.1.4. Ant
<a name="ant"></a></div>
<p>While Balloon tip doesn't come with any Ant build files, it's
quite
easy to automatically generate them if you have Maven installed:</p>
<ol>
<li>If you haven't already done so, download and unzip the
latest Balloon tip release from <a target="_blank" href="https://balloontip.dev.java.net/">
https://balloontip.dev.java.net/</a>.</li>
<li>Using your command-line-interface, navigate to the "src"
folder.</li>
<li>Run the command&nbsp;<code>mvn ant:ant</code>
to generate Ant build files
for Balloon tip. (You'll need <a href="http://maven.apache.org/download.html" target="_blank">Maven</a>
to be able to execute this command.)</li>
<li>After
Maven has successfully generated Ant build files, you'll be able to run
the usual set of Ant tasks: compile, jar, javadoc, clean, ...</li>
</ol>
</div>
</div>
<div class="subSection">
<div class="title"> 2.2. Creating your own BalloonTipStyle<a name="creatingyourownballoontipstyle"></a></div>
<p>Creating a new balloon tip style is fairly easy if you're a
bit familiar with Java's <code>Graphics</code> API. To
start making your own balloon tip style, you should extend the <code>BalloonTipStyle</code>
class. In this class, you should at least override these two methods:</p>
<ul>
<li><code>public Insets getBorderInsets(Component c)</code></li>
<li><code>public void paintBorder(Component c, Graphics
g, int x, int y, int width, int height)</code></li>
</ul>
<p><code>getBorderInsets</code> is a method that
determines where the actual contents of the balloon tip (the text, the
close button, ...) should go. (If you're familiar with Cascading Style
Sheets (CSS), you should think of <code>getBorderInsets</code>
as a method that returns the padding of your balloon tip.) What
you should do is return an <code>Insets</code> object,
which holds four integers. To determine these four, take a look at this
picture:</p>
<div class="image"> <img src="images/Insets.png" alt="These four values are needed by getBorderInsets" /><br />
These four values are needed by <code>getBorderInsets</code>
</div>
<p>Suppose the green rectangle in the above picture represents
where the contents of the balloon tip should come. The implementation
of <code>getBorderInsets</code>&nbsp;then looks like
this:</p>
<p><code>return new Insets(top, left, bottom, right);</code></p>
<p>The second method you should implement, <code>paintBorder</code>,
draws the balloon tip on a <code>Graphics</code> instance.
You've got a couple of different values to work with here. The obvious
ones are the <code>x</code>, <code>y</code>, <code>width</code>
and <code>height</code>-parameters. <code>x</code>
and <code>y</code> determine the top-left coordinate of
your drawing canvas, whereas <code>width</code> and <code>height</code>
obviously represent the width and height of the drawing canvas. <br />
Beside these parameters, you should also take into account the current
values of the fields in <code>BalloonTipStyle</code>: <code>horizontalOffset</code>,
<code>verticalOffset</code>, <code>flipX</code>
and <code>flipY</code>. The meaning of these fields should
become clear when looking at this image:</p>
<div class="image"> <img src="images/Flips.png" alt="A BalloonTipStyle should respect the current values of horizontalOffset, verticalOffset, flipX and flipY" /><br />
A <code>BalloonTipStyle</code> should respect the current
values of <code>horizontalOffset</code>, <code>verticalOffset</code>,
<code>flipX</code> and <code>flipY</code> </div>
<p>Keep in mind that you must take into account <code>flipX</code>
and <code>flipY</code> when implementing <code>getBorderInsets</code>,
as they have their effect on border insets!</p>
<p>Apart from <code>getBorderInsets</code> and <code>paintBorder</code>,
you may also want to override the methods <code>getMinimalHorizontalOffset</code>
and <code>isBorderOpaque</code>. Override <code>getMinimalHorizontalOffset</code>
to define the minimum value of the horizontal offset. You may want to
do this if your balloon tip starts to look funny if you go below (or
above) a certain horizontal offset. Balloon tip positioners will then
respect the minimum horizontal offset you've defined. Secondly, you
should override <code>isBorderOpaque</code> if you wish to
use transparency effects. If so, simply make the method return false
and you're allowed to use transparent colors.</p>
<p>Apart from all of the above, there really is nothing else to
know
about balloon tip styles. However, I did assume you are familiar with
the Java <code>Graphics</code> API. If you're not, I
recommend you to take a couple of tutorials (such as <a href="http://java.sun.com/docs/books/tutorial/2d/index.html" target="_blank">http://java.sun.com/docs/books/tutorial/2d/index.html</a>),
or take a look at the code of the existing styles in Balloon tip.</p>
</div>
<div class="subSection">
<div class="title"> 2.3. Creating your own
BalloonTipPositioner<a name="creatingyourownballoontippositioner"></a></div>
<p>The task of a balloon tip positioner is to define the
behaviour of a balloon tip. This means it controls the position of the
balloon tip, the horizontal and vertical offset of the balloon tip and
whether the balloon tip should be flipped or not. The best way to learn
how to create your own <code>BalloonTipPositioner</code>
is by looking at an example. The following example demonstrates a very
simple positioner that will place the balloon tip at a fixed location
relative to the attached component:</p>
<pre><code><br />public class SimpleTipPositioner extends BalloonTipPositioner {<br />	int x = 0; // Current X-coordinate of the top-left corner of the bounding box around the balloon tip<br />	int y = 0; // Current Y-coordinate of the top-left corner of the bounding box around the balloon tip<br /><br />	/* The balloon tip will call this method every time it wants to re-draw itself.<br />	* The parameter of this function, attached, is the Rectangle that the balloon tip should attach itself to. */<br />	public void determineAndSetLocation(Rectangle attached) {<br />		/* Calculate the coordinates of the top-left corner of the bounding box around the balloon tip<br />		* This positioner will place the balloon tip above the attached Rectangle. */<br />		x = attached.x;<br />		y = attached.y - balloonTip.getPreferredSize().height;<br /><br />		// Now move the balloon tip to the position we've just calculated<br />		balloonTip.setBounds(x, y, balloonTip.getPreferredSize().width, balloonTip.getPreferredSize().height);<br />		balloonTip.validate();<br />	}<br /><br />	/* This method should return the location of the balloon's tip */<br />	public Point getTipLocation() {<br />		/* You may use the last position calculated in determineAndSetLocation to calculate the tip's location.<br />		* The fields x and y now contain the position of the top-left corner of the bounding box of the balloon tip. */<br />		return new Point(x + 20, y + balloonTip.getPreferredSize().height);<br />	}<br /><br />	/* Whenever a balloon tip's style is changed (This includes setting it for the first time..), this method is called.<br />	*&nbsp;Within this method, the positioner should take care of properly setting up this new style. */<br />	protected void onStyleChange() {<br />		balloonTip.getStyle().setHorizontalOffset(20);<br />		balloonTip.getStyle().setVerticalOffset(20);<br /></code><code>		balloonTip.getStyle().flipX(false);<br />		balloonTip.getStyle().flipY(false);</code><br /><code>	}<br />}</code></pre>
<p>Using this positioner will produce the following result:</p>
<div class="image"> <img src="images/CustomPositioner.png" alt="A BalloonTip with a simple custom-made BalloonTipPositioner" /><br />
A <code>BalloonTip</code> with a simple custom-made <code>BalloonTipPositioner</code>
</div>
<p>Here's the same picture once more, but this time it also shows
the
various variables that were used:</p>
<div class="image"> <img src="images/PositionerVariables.png" alt="The variables that were used when calculating the balloon tip's position" /><br />
The variables that were used when calculating the balloon tip's
position </div>
<p>This image may also prove useful; it shows the different
settings of the balloon tip's style:</p>
<div class="image"> <img src="images/Flips.png" alt="Don't forget to set these variables of the balloon tip's style: horizontalOffset, verticalOffset, flipX and flipY" /><br />
Don't forget to set these variables of the balloon tip's style: <code>horizontalOffset</code>,
<code>verticalOffset</code>, <code>flipX</code>
and <code>flipY</code> </div>
<p>After examining this example, you can&nbsp;conclude that:</p>
<ul>
<li> The positioner has the responsibility to set the balloon
tip's location.</li>
<li>The positioner has the responsibility to set the balloon
tip style's offsets and whether it should flip.</li>
<li>You can retrieve most necessary information for your
calculations from the balloonTip field. (For example, if you need the
window's width, you can use <code>balloonTip.getTopLevelContainer().getWidth()</code>)
If you do need extra information, you'll need to ask for it in your
positioner's constructor.</li>
<li>You'll need to create fields that contain the current state
of the positioner, or you won't be able to calculate the tip location
in <code>getTipLocation</code>.</li>
</ul>
<p>Lastly, a couple of pointers that you may find useful:</p>
<ul>
<li>Whether you're flipping the balloon tip's style or not, the
bounding box around the balloon tip won't ever flip, so you'll always
need to calculate its top-left corner! (By the way, if you're unsure
about the meaning of a bounding box: It's the smallest rectangle that
contains the entire balloon tip..)</li>
<li>If a balloon tip is flipped over a vertical axis, the
horizontal offset has flipped sides as well!</li>
<li>You may want to draw the balloon tip's behaviour with a
couple of doodles if things get a little complex.</li>
</ul>
<p>While this particular example did not produce anything
spectacular, you can do some neat things with your own balloon tip
positioner. You could implement a positioner that, for example: always
puts the balloon's tip in the center, or tries to avoid overlapping
with some other components, or tries to never move the balloon tip
outside a certain area, or ...</p>
</div>
</div>
<div class="section">
<div class="title"> 3. Release notes<a name="releasenotes"></a></div>

<ul>
<li><strong>1.2.1</strong>
<ul>
	<li>Improvement: Removed redundant refreshLocation() call when constructing a CustomBalloonTip.</li>
	<li>Bug fix: Fixed issue where a balloon tip is shown initially if it is attached to a component that is currently outside the visible region of a viewport.</li>
	<li>Bug fix: Fixed issue where a balloon tip is shown if it is attached to a component on a tab that is currently not shown.</li>
</ul>
</li>
<li><strong>1.2</strong>
<ul>
	<li>Change: Balloon tip's license was changed from LGPL v2.1 (or higher) to the 3-Clause BSD License.</li>
	<li>New feature: Any type of balloon tip can now be embedded in (multiple nested) scroll panes. These scroll panes are detected automatically as well.<br />(As a consequence, the CustomBalloonTip.setViewport() method is no longer needed and is removed.)</li>
	<li>New feature: Two new balloon tip styles are added: IsometricBalloonTipStyle and ToolTipBalloonTipStyle.</li>
	<li>Bug fix: Fixed rare issue where a balloon tip is positioned incorrectly initially.</li>
	<li>Bug fix: When using a balloon tip as a tooltip, the balloon tip is now hidden when the attached component is clicked.</li>
</ul>
</li>
<li><strong>1.1.1</strong>
<ul>
<li>Bug fix: Fixed rare issue where balloon tips dissappear
if you resize the window, go to another tab, then go back.</li>
<li>Bug fix: Fixed issue where a balloon tip is visible at
instantiation when it shouldn't be.</li>
<li>Improvement: Added ToolTipUtils.toolTipToBalloon() to
turn balloon tooltips back to normal.</li>
</ul>
</li>
<li><strong>1.1</strong>
<ul>
<li>New feature: The contents of a BalloonTip can now be
just about any type of JComponent. (You can even add balloon tips to
components within balloon tips..)</li>
<li>New feature: New positioner that ensures a balloon tip
is always centered relative to its attached component.</li>
<li>New feature: You can now set a balloon tip's opacity.
There also are utility functions to add fading effects to your balloon
tips.</li>
<li>New feature: More getters and setters. Every aspect of
a balloon tip can now be adjusted, including the attached component and
the top-level container.</li>
<li>Improvement: The logic that determines a balloon tip's
visibility has become much simpler. You can now safely call
setVisible(false) to hide a balloon tip.</li>
<li>Improvement: Creating your own BalloonTipPositioner has
been more simplified.</li>
<li>Improvement: The drawing code for some balloon tip
styles is slightly improved.</li>
<li>Change: We switched the LGPL v3 license back to LGPL
v2.1 (or higher, at your option), such that even more projects can make
use of Balloon tip.</li>
<li>Change: Rather than letting you tweak a few aspects of
a balloon tip's close button, you now simply have direct access to the
button.</li>
<li>Change: The enableClickToHide() and
enabledClickToClose() are replaced by addDefaultMouseListener().</li>
<li>Bug fix: Some listeners were not removed when closing a
BalloonTip.</li>
<li>Bug fix: A balloon tooltip now properly hides itself
when the mouse leaves the attached component.</li>
</ul>
</li>
<li><strong>1.0</strong>
<ul>
<li>Switched from Ant to Maven.</li>
<li>Switched to the regular x.x version numbering scheme,
instead of using the release date to identify a version</li>
</ul>
</li>
<li><strong>2008-11-14</strong>
<ul>
<li>Added GNU Lesser Public License v3 preamble to all of
the project's source files</li>
</ul>
</li>
<li><strong>2008-10-10</strong>
<ul>
<li>Bug fix: Balloon tips can now be used within JApplets</li>
<li>Added a simple example application to show balloon tips
now work in applets</li>
<li>The Ant build file now always compiles in Java 5</li>
</ul>
</li>
<li><strong>2008-09-23</strong>
<ul>
<li>BalloonTipStyle: Create new looks for balloon tips by
extending the BalloonTipStyle-class</li>
<li>BalloonTipPositioner: Control the way a balloon tip
positions itself by extending the BalloonTipPositioner-class</li>
<li>Added 3 new balloon tip styles: Minimal, Modern and
Textured</li>
<li>CustomBalloonTip: allows you to attach a balloon tip to
a certain offset rectangle within a JComponent</li>
<li>TablecellBalloonTip: allows you to attach a balloon tip
to a JTable cell</li>
<li>TimingUtils: Automatically close a balloon tip after a
certain time</li>
<li>ToolTipUtils: Turn a balloon tip into a tooltip</li>
<li>Balloon tips will now try their best to stay visible;
if a balloon tip collides with the window's border, it will either
shift or flip itself</li>
<li>Balloon tips now have the option to close or hide
themselves by clicking anywhere on the balloon tip</li>
<li>More constructors, ranging from easy-to-use to
full-fledged</li>
<li>The CompleteExample application shows off most of the
project's features</li>
<li>More example applications were added</li>
<li>The project now has a user manual</li>
<li>The project now has an Ant build file</li>
<li>Bug fixes: The balloon tip will no longer throw a
NullPointerException if you try to create it before calling pack() on
the top level container</li>
</ul>
</li>
<li><strong>2007-12-30</strong>
<ul>
<li>The balloon tip can now be displayed above or below on
either side of the attached component</li>
<li>The location of the triangle tip can be set manually to
the center and all "corners" of the attached component (useful for
icons)</li>
<li>The border width of the close button can be set</li>
<li>The API has changed a little bit - sorry for that</li>
<li>A bigger change is the move to Java 5. It has been out
now for a while, so I don't think it will be a big problem. If you are
locked down to an older version, you can still make it work for you by
replacing the enumerations in the source code with constants</li>
<li>Also noteworthy: The release package now contains an
executable JAR</li>
</ul>
</li>
<li><strong>2007-05-15</strong>
<ul>
<li>One new flavor: Rounded balloon tips</li>
<li>Close buttons</li>
<li>Revised example application</li>
<li>Some other but minor improvements like expanded
customizability</li>
<li>The API has been changed rather drastically</li>
</ul>
</li>
<li><strong>2007-03-30</strong>
<ul>
<li>Bug fixed: Support for JInternalFrame was missing</li>
<li>Bug fixed: Location of BalloonTip component was
miscalculated in more complex layouts</li>
</ul>
</li>
<li><strong>2007-03-01</strong>
<ul>
<li>Initial release</li>
</ul>
</li>
</ul>
</div>
<div id="footer" class="balloontip"> Contact: <a href="mailto:nferno@dev.java.net">nferno@dev.java.net</a>
or <a href="mailto:bernhard_pauler@dev.java.net">bernhard_pauler@dev.java.net</a>
| W3C xHTML &amp; CSS validated</div>
</body></html>